% chapter03.tex

 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %                                                                           %
 %    YABBY documentation                                                    %
 %    Copyright (C) 2007 Vladimir Likic                                      %
 %                                                                           %
 %    The files in this directory provided under the Creative Commons        %
 %    Attribution-NonCommercial-NoDerivs 2.1 Australia license               %
 %    http://creativecommons.org/licenses/by-nc-nd/2.1/au/                   %
 %    See the file license.txt                                               %
 %                                                                           %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\setcounter{section}{0}

\chapter{Command reference}

\section{General commands}

General commands are related to the basic Yabby functions, such as
control of the workspace, and are not related to any specific area
of application. 

% ### NEW COMMAND ###

\subsection[delete]{ \fbox{\tt delete} }

\index{delete}

% Concise explanation

Deletes objects from the workspace.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt delete OBJECT.PROPERTY}

% 2. Options

\item{Options:}
\begin{description}
{\em None}
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item If PROPERTY equals '*' (no quotes) all properties of OBJECT will
be deleted.
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> delete sp.seq

 [ 'sp.seq' deleted ]
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[dump]{ \fbox{\tt dump} }

\index{dump}

% Concise explanation

Dumps the current workspace to a file, which later can be restored
with 'restore'.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt dump SESSION\_NAME}

% 2. Options

\item{Options:}
\begin{description}
{\em None}
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item This command saves the current Yabby session in the file
 SESSION\_NAME.tar.gz in the current directory.
\item Currently works only on system that have GNU tar command.
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> dump tmpsession

 Yabby session archived as 'tmpsession.tar.gz'
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####


% ### NEW COMMAND ###

\subsection[flush]{ \fbox{\tt flush} }

\index{flush}

% Concise explanation

Deletes everything from the workspace.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt flush}

% 2. Options

\item{Options:}
\begin{description}
{\em None}
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
{\em None}
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> flush

 [ workspace flushed ]
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####


% ### NEW COMMAND ###

\subsection[license]{ \fbox{\tt license} }

\index{license}

% Concise explanation

Prints the Yabby license.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt license}

% 2. Options

\item{Options:}
\begin{description}
{\em None}
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
{\em None}
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> license


                    GNU GENERAL PUBLIC LICENSE
                       Version 2, June 1991

 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
                          675 Mass Ave, Cambridge, MA 02139, USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

                            Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
....
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[help]{ \fbox{\tt help} }

\index{help}

% Concise explanation

Prints help pages.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt help [ COMMAND ]}

% 2. Options

\item{Options:}
\begin{description}
{\em None}
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item If no argument is given the list of all available commands will
be printed. If a command name is given the help about a particular
command will be printed. 
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> help quit

 Exits Yabby

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####


% ### NEW COMMAND ###

\subsection[print]{ \fbox{\tt print} }

\index{print}

% Concise explanation

Prints an object on the terminal screen or to a file.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt print [ options ] OBJ\_NAME.PROPERTY}

% 2. Options

\item{Options (general):}
\begin{description}
\item -f FILE\_NAME -- print to a file instead on the terminal screen.
\end{description}

\item{Options (seq objects only):}
\begin{description}
\item -l -- print the sequence as the three-letter code.
\item -c -- print the sequences as the CSV table.
\item -n N -- print N residues per line (both when printing one- and
 three-letter codes).
\item -t N -- truncate each sequence at N letters when writing
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item Currently supported objects for printing are 'seq', 'motif',
and 'blastg'. 
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item Print the sequence object tom20.seq
\begin{verbatim}
yabby> print tom20.seq

>A.thaliana [ A.thaliana ]
MDTETEFDRILLFEQIRQDAENTYKSNPLDADNLTRWGGVLLELSQFHSISDAKQMIQEA
ITKFEEALLIDPKKDEAVWCIGNAYTSFAFLTPDETEAKHNFDLATQFFQQAVDEQPDNT
HYLKSLEMTAKAPQLHAEAYKQGLGSQPMGRVEAPAPPSSKAVKNKKSSDAKYDAMGWVI
LAIGVVAWISFAKANVPVSPPR
>O.sativa [ O.sativa ]
MDMGAMSDPERMFFFDLACQNAKVTYEQNPHDADNLARWGGALLELSQMRNGPESLKCLE
DAESKLEEALKIDPMKADALWCLGNAQTSHGFFTSDTVKANEFFEKATQCFQKAVDVEPA
NDLYRKSLDLSSKAPELHMEIHRQMASQASQAASSTSNTRQSRKKKKDSDFWYDVFGWVV
LGVGMVVWVGLAKSNAPPQAPR
>L.esculentum [ L.esculentum ]
MDMQSDFDRLLFFEHARKTAETTYATDPLDAENLTRWAGALLELSQFQSVSESKKMISDA
ISKLEEALEVNPQKHDAIWCLGNAYTSHGFLNPDEDEAKIFFDKAAQCFQQAVDADPENE
LYQKSFEVSSKTSELHAQIHKQGPLQQAMGPGPSTTTSSTKGAKKKSSDLKYDVFGWVIL
AVGLVAWIGFAKSNMPXPAHPLPR
>S.tuberosum [ S.tuberosum ]
MEMQSEFDRLLFFEHARKSAETTYAQNPLDADNLTRWGGALLELSQFQPVAESKQMISDA
TSKLEEALTVNPEKHDALWCLGNAHTSHVFLTPDMDEAKVYFEKATQCFQQAFDADPSND
LYRKSLEVTAKAPELHMEIHRHGPMQQTMAAEPSTSTSTKSSKKTKSSDLKYDIFGWVIL
AVGIVAWVGFAKSNMPPPPPPPPQ
>P.taeda [ P.taeda ]
MEEMAIPQSDFDRLLFFEGARKAAENTYAVNPEDADNLTRWGGALLELSQFQQGPDCVKM
VKDAVSKLEEALKISPNKHDTLWCLGNAHTSHAFLIPEHEVAKIYFKMASKYFQQAVEQD
PTNELYRKSLELTEKAPELHLEVHKQILNPQSVAAGSSTVSNLKGSRKKKSSDLKYDIMG
WIVLAVGIAAWVGMAKSHVPPPPML
>G.max [ G.max ]
MDLQQSEFDRLLFFEHARKAAEAEYEKNPLDADNLTRWGGALLELSQFQSFPESKKMTQE
AVSKLEEALAVNPKKHDTLWCLGNAHTSQAFLIPDQEEAKVYFDKAAVYFQQAVDEDPSN
ELYRKSLEVAAKAPELHVEIHKQGFGQQQQAAATAGSSTSASTNTQKKKKSSDLKYDIFG
WIILAVGIVAWVGFAKSNLPPPPPPPPR
>Z.mays [ Z.mays ]
MEMGGMSDAERLFFFEMACKNSEVAYEQNPNDADNLTRWGGALLELSQVRTGPDSLKLLE
DAEAKLEEALQIDPNKSDALWCLGNAQTSHGFFTPDNAIANEFFTKATGCFQKAVDVEPA
NELYRKSLDLSMKAPELHLEIQRQMVSQAATQASSASNPRQSRKKKDNDFWYDVCGWVIL
GAGIVAWVGLARASMPPPTPPAR
\end{verbatim}

\item Print the sequence object tom20.seq to a file 'tom20.txt' 
\begin{verbatim}
yabby> print -f tom20.txt tom20.seq

 'tom20.seq' written to the file 'tom20.txt'
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} The object to be printed must exist in the
workspace.

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} \_print\_seq.pl, \_print\_motif.pl, \_print\_blastg.pl

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[restore]{ \fbox{\tt restore} }

\index{restore}

% Concise explanation

Restores Yabby session saved with the command 'dump'

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt restore SESSION\_NAME}

Where SESSION\_NAME is the archive name used when dumping
the session.

% 2. Options

\item{Options:}
\begin{description}
{\em None}
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item The session will be restored from a file named SESSION\_NAME.tar.gz.
\item Relies on GNU tar and gzip commands. These must be in the
 executable path.
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> restore tmpsession

 Yabby session 'tmpsession' restored
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####


% ### NEW COMMAND ###

\subsection[what]{ \fbox{\tt what} }

\index{what}

% Concise explanation

Shows objects currently in the workspace.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt what}

% 2. Options

\item{Options:}
\begin{description}
{\em None}
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
{\em None}
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> what

    objects        properties
  ------------------------------
    tom20          seq           

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ##############################################################
\section{Sequence commands}
% ##############################################################

% ### NEW COMMAND ###

\subsection[seq\_comment]{ \fbox{\tt seq\_comment} }

\index{seq\_comment}

% Concise explanation

Modifies sequence comments to add a unique number.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt seq\_comment OBJ\_NAME}

where OBJ\_NAME is the name of an existing sequence object.

 The sequence object with modified comments overwrites OBJ\_NAME.
 The comment for each sequence is modified to prepend N- where
 N is the order of the sequence.  For example, if the sequence
 comment was Q9JXN6, and was first in the sequence object, its
 comment will be modified to 1-Q9JXN6.

% 2. Options

\item{Options:} {\em None}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> seq_comment cad3

 Comments modified in 3 sequence(s).
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} seq

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[seq\_compl]{ \fbox{\tt seq\_compl} }

\index{seq\_compl}

% Concise explanation

Calculates sequence complement (for DNA sequences).

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt seq\_compl [ options ] OBJ\_NAME OBJ\_NAME\_NEW}

 Where OBJ\_NAME is the name of an existing sequence object,
 the complement sequence will be saved under the name
 OBJ\_NAME\_NEW. The sequence OBJ\_NAME must be a DNA sequence.

% 2. Options

\item{Options:}
\begin{description}
\item -r -- Calculate the reverse complement.
\end{description}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> seq_compl dna dna_c

 'dna' contains 1 sequence(s)
 Working on 'chr01'

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} seq

% 6. Objects 

\item{Creates objects:} seq

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[seq\_genbank]{ \fbox{\tt seq\_genbank} }

\index{seq\_genbank}

% Concise explanation

Fetch a sequence from GenBank.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt seq\_genbank [ options ] IDENTIFIER OBJ\_NAME}

 Fetch a sequence from GenBank using an identifier such as the
 sequence accession number (default), version, GI number or
 unique ID (locus) and save the sequence under the name OBJ\_NAME.

% 2. Options

\item{Options:}
\begin{description}
\item -a ACCESSION\_NUMBER (default) -- fetch sequence by accession number
\item -v VERSION -- fetch sequence by version number
\item -g GI\_NUMBER -- fetch sequence by GI number
\item -i UNIQUE\_ID -- fetch sequence by unique ID
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item This command requires Bioperl's Bio::DB module.
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> seq_fetch -a J00522 mig

 Saving 'J00522' as 'mig'

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} seq

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[seq\_info]{ \fbox{\tt seq\_info} }

\index{seq\_info}

% Concise explanation

Prints information about the sequence object.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt seq\_info [ options ] OBJ\_NAME}

Where OBJ\_NAME is the name of an existing sequence object.

% 2. Options

\item{Options:}
\begin{description}
\item -l -- long output.  When multiple sequences are present,
            print the number of residues for each sequence.
            By default, only a short summary is printed.
\item -n -- print only the number of residues in each sequence
\end{description}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> seq_info cad3

 'cad3' contains 3 sequence(s)
   min number of residues: 192 (sequence 'Q53650_STAAU')
   max number of residues: 193 (sequence 'Q97PJ0_STRPN')

\end{verbatim}

\item
\begin{verbatim}
yabby> seq_info -l cad3

 'cad3' contains 3 sequence(s)
  1 -> Q53650_STAAU, 192 residues
  2 -> Q97PJ0_STRPN, 193 residues
  3 -> P95773_STALU, 192 residues

\end{verbatim}

\item
\begin{verbatim}
yabby> seq_info -n cad3

 'cad3' contains 3 sequence(s)
192
193
192

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} seq

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[seq\_load]{ \fbox{\tt seq\_load} }

\index{seq\_load}

% Concise explanation

Loads sequence(s) from the database file.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt seq\_load [ options ] DBA\_FILE OBJ\_NAME}

Where DBA\_FILE is the name of the database file. OBJ\_NAME is
the internal Yabby name for the sequence(s).

% 2. Options

\item{Options:}
\begin{description}
\item -a -- append sequences to an already existing sequence
object OBJ\_NAME
\item -f -- the file format is FASTA (default)
\item -b -- the file format is BLOCKS
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item Only BLOCKS format written by MEME \cite{meme} output was tested.
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> seq_load cad3.fas cad3

 Reading the file 'cad3.fas' ..
 3 sequence(s) found.
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} seq

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[seq\_op]{ \fbox{\tt seq\_op} }

\index{seq\_op}

% Concise explanation

Calculates union/intersection/difference of two sequence objects
by using the sequence IDs.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt seq\_op [ options ] SEQ1\_OBJ SEQ2\_OBJ OBJ\_NAME}

Calculates union/intersection/difference of two sequence objects
SEQ1\_OBJ and SEQ2\_OBJ, and stores the result as the sequence
object OBJ\_NAME.

% 2. Options

\item{Options:}
\begin{description}
\item -u -- calculate the union (default)
\item -i -- calculate the intersection
\item -d -- calculate the difference
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item The calculation will fail if there are duplicate sequences in
      one set. For example, if two sets of sequences have no sequence
      in common, but one set of sequences contains two copies of the
      sequence 'F36.5845', the intersection of the two sets will contain
      this sequence.
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> seq_op -i cad cad3 cadi

 Found 6 sequence(s) in 'cad'
 Found 3 sequence(s) in 'cad3'
  INTERSECTION contains 3 sequence(s)
  DIFFERENCE contains 3 sequence(s)
  UNION contains 6 sequence(s)
 [ Saving INTERSECTION as 'cadi' ]

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} seq

% 6. Objects 

\item{Creates objects:} seq

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####


% ### NEW COMMAND ###

\subsection[seq\_os]{ \fbox{\tt seq\_os} }

\index{seq\_os}

% Concise explanation

Inserts additional information in sequence comments, where
additional information is read from an external file.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt seq\_os FILE\_NAME OBJ\_NAME}

Where FILE\_NAME is the file which contains pairs (sequence
ID, additional information), and OBJ\_NAME is the name of an
existing sequence object. FILE\_NAME must include all sequence
IDs present in the OBJ\_NAME.

% 2. Options

\item{Options:}
\begin{description}
{\em None}
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
% {\em None} - Uncomment this and delete line below if no notes 
\item The object OBJ\_NAME will be overwritten with altered comments
to include the additional information for each sequence.
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item Insert organism names in 21 sequences stored under the
name 'cam.seq'.
\begin{verbatim}
yabby> seq_os sprot_test.dat.os cam

 Reading the file 'sprot_test.dat.os' ...
 21 sequences to process.

 All done.
 [ seq_os: 'cam.seq' exists, overwritten ]
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em seq}

% 6. Objects 

\item{Creates objects:} {\em seq} (overwrites the original seq object)

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[seq\_pattern]{ \fbox{\tt seq\_pattern} }

\index{seq\_pattern}

% Concise explanation

Searches for letter pattern in a sequence object.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt seq\_pattern [ options ] PATTERN OBJ\_NAME}

Searches for pattern PATTERN in sequences OBJ\_NAME.
Where OBJ\_NAME is the name of an existing sequence object.

% 2. Options

\item{Options:}
\begin{description}
\item -c -- Match the comment not the sequence.
\item -s NAME -- extract the matching sequences and save under
    the name NAME.
\item -n -- Print the matching sequences and the residue position
    where the pattern matches.
\end{description}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> seq_pattern IDY cad3

 'IDY' matches in 'Q53650_STAAU'
 'IDY' matches in 'Q97PJ0_STRPN'
 3 sequences examined, 2 match(es) found

\end{verbatim}

\item
\begin{verbatim}
yabby> seq_pattern -c STAA cad3

 'STAA' matches in 'Q53650_STAAU'
 3 sequences examined, 1 match(es) found

\end{verbatim}

\item
\begin{verbatim}
yabby> seq_pattern -s IDY_matches IDY cad3

 'IDY' matches in 'Q53650_STAAU'
 'IDY' matches in 'Q97PJ0_STRPN'
 3 sequences examined, 2 match(es) found
 Saving matches as 'IDY_matches'

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} seq

% 6. Objects 

\item{Creates objects:} (with option -s) seq

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[seq\_pick]{ \fbox{\tt seq\_pick} }

\index{seq\_pick}

% Concise explanation

Extracts a subset of sequences from the sequence object.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt seq\_pick [ options ] OBJ\_NAME OBJ\_NAME\_NEW}

 where OBJ\_NAME is the name of an existing sequence object,
 and OBJ\_NAME\_NEW is the name of the sequence object to
 be created.

% 2. Options

\item{Options:}
\begin{description}
\item -n RANGE -- extract the sequence by sequence number. The
 parameter RANGE can be a single integer, in which the
 sequence with this sequence number will be extracted.
 Alternatively, RANGE can contain two integers separated
 by a colon such as N:M. In this case the sequences which
 have the sequence number between N and M will be extracted
 (inclusive).
\item -q SEQID -- pick a sequence with the sequence ID SEQID
\item -l MIN:MAX -- pick sequences whose length is between MIN and MAX
\end{description}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> seq_pick -q Q53650_STAAU cad3 s1

 Fetching the sequence 'Q53650_STAAU'
 Saving the extracted sequence as 's1'

\end{verbatim}

\item
\begin{verbatim}
yabby> seq_pick -n 2 cad3 s2

 Fetching the sequence 2 ('Q97PJ0_STRPN')
 Saving the extracted sequence as 's2'

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} seq

% 6. Objects 

\item{Creates objects:} seq

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[seq\_sprot\_os]{ \fbox{\tt seq\_sprot\_os} }

\index{seq\_sprot\_os}

% Concise explanation

Inserts the organism name into sequence comments by using
the local Swiss-Prot database file.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt seq\_sprot\_os DBA\_FILE OBJ\_NAME}

Where DBA\_FILE is the local database file in the Swiss-Prot
format, and OBJ\_NAME is the name of an existing sequence
object. The object OBJ\_NAME will be overwritten with altered
comments to include the organism name for each sequence.

% 2. Options

\item{Options:}
{\em None}

% 3. Notes

\item{Notes:}
\begin{description}
\item This command overwrites the original sequence.
\end{description}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item Fetch the organism name (OS) field from the Swiss-Prot file,
'sprot\_test.dat', and insert this in the sequence comment of three
sequences saved as 'aqr1':
\begin{verbatim}
yabby> seq_sprot_os sprot_test.dat aqr1 

 3 sequences to process.
 Printing dot per processed sequence:
 ...
 All done.
 [ seq_sprot_os: 'aqr1.seq' exists, overwritten ]
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em seq}

% 6. Objects 

\item{Creates objects:} {\em seq} (overwrites the original seq object)

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####


% ### NEW COMMAND ###

\subsection[seq\_strip]{ \fbox{\tt seq\_strip} }

\index{seq\_strip}

% Concise explanation

Strips a portion of a sequence.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt seq\_strip begin:end OBJ\_NAME OBJ\_NAME\_NEW}

Where OBJ\_NAME is the name of an existing sequence object, and
begin:end are the first and last residue positions to strip (inclusive).
The resulting object will be saved under the name OBJ\_NAME\_NEW.

If more than one sequence is present in the sequence object,
all will be stripped and saved under the new name.

In stripped sequences, IDs are set to ORIGINALID\_begin:end.

% 2. Options

\item{Options:} {\em None}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> seq_strip 21:40 cad3 cad3portion

 'cad3' contains 3 sequence(s)
 stripping 'Q53650_STAAU'
 stripping 'Q97PJ0_STRPN'
 stripping 'P95773_STALU'

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} seq

% 6. Objects 

\item{Creates objects:} seq

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[seq\_uniprot]{ \fbox{\tt seq\_uniprot} }

\index{seq\_uniprot}

% Concise explanation

Fetch a sequence from SwissProt.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt seq\_uniprot [ options ] LOCATION IDENTIFIER OBJ\_NAME}

 Fetch a sequence from SwissProt using an identifier such as the
 sequence accession number (default) or
 unique ID and saves the sequence under the name OBJ\_NAME.

% 2. Options

\item{Options:}
\begin{description}
\item -l LOCATION -- possible values (australia,canada,china,korea,switzerland,taiwan,us)
\item -a ACCESSION\_NUMBER -- fetch sequence by accession number (default)
\item -i UNIQUE\_ID -- fetch sequence by unique ID

\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item This command requires Bioperl's Bio::DB module.
\end{enumerate}

% 4. Examples

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> seq_uniprot -a P43780 -l australia miga

 Saving 'P43780' as 'miga'

\end{verbatim}

\end{enumerate}

% 5. Requirements

\item{Requirements:} {\em None}

% 6. Objects

\item{Creates objects:} seq

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[seq\_unique]{ \fbox{\tt seq\_unique} }

\index{seq\_unique}

% Concise explanation

Finds unique sequences in one sequence object relative to another
by comparing sequence strings.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt seq\_unique SEQ1\_OBJ SEQ2\_OBJ OBJ\_NAME}

This command will find the unique sequences in SEQ1\_OBJ compared
to SEQ2\_OBJ, and store these unique sequences as OBJ\_NAME.

% 2. Options

\item{Options:} {\em None}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item Sequences present in the first sequence object and not present
 in the second second object are calculated. Therefore the order
 of sequence objects given in the argument matters.
\item This command compares sequence letters as opposed to sequence
 IDs (compared to seq\_op). Two sequences are identical if they
 are an exact letter-by-letter match.
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> seq_unique cad cad3 caduniqincad

 3 unique sequences found.
 Saving sequences as 'caduniqincad'

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} seq

% 6. Objects 

\item{Creates objects:} seq

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####


% ##############################################################
\section{Swiss-Prot related commands}
% ##############################################################

% ### NEW COMMAND ###

\subsection[sprot\_fetch]{ \fbox{\tt sprot\_fetch} }

\index{sprot\_fetch}

% Concise explanation

Fetches a sequence from a Swiss-Prot local file database
by its ID.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt sprot\_fetch DBA\_FILE SPROT\_ID OBJ\_NAME}

Where DBA\_FILE is the database is the Swiss-Prot format,
and SPROT\_ID is the Swiss-Prot sequence ID, and OBJ\_NAME
is the name under which the sequence will be saved in the
workspace.

% 2. Options

\item{Options:}
{\em None}

% 3. Notes

\item{Notes:}
{\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item Fetch the sequence '110KD\_PLAKN' from the Swiss-Prot
file 'sprot\_test.dat':
\begin{verbatim}
yabby> sprot_fetch sprot_test.dat 110KD_PLAKN plakn

 Sequence '110KD_PLAKN' found.
 [ Saving as 'plakn.seq' ]
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} {\em seq}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[sprot\_os]{ \fbox{\tt sprot\_os} }

\index{sprot\_os}

% Concise explanation

Extracts sequence ID and organism name from the Swiss-Prot
sequence database file.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt sprot\_os DBA\_FILE OUT\_FILE}

Where DBA\_FILE is the name of the sequence database file
in the Swiss-Prot format, and OUT\_FILE is the name of the
output file to be created, containing pairs (sequence ID,
organism name).

% 2. Options

\item{Options:}
{\em None}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item This command is designed to work with the command 'seq\_os'.
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item Extract the organism names (Swiss-Prot OS field) from the
file 'uniprot.dat', and save as the file 'uniprot.dat.os':
\begin{verbatim}
yabby> sprot_os uniprot.dat uniprot.dat.os

 Processing the database file 'uniprot.dat' ..
 Printing a dot per 10000 processed sequences:
 ............................................................
 ............................................................
 ............................................................
 ............................................................
 ............................................................
 ............................................................
 ............................................................
 ............................................................
 ...............................................

 All done.
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ##############################################################
\section{HMMER commands}
% ##############################################################

% ### NEW COMMAND ###

\subsection[hmm\_score\_extract]{ \fbox{\tt hmm\_score\_extract} }

\index{hmm\_score\_extract}

% Concise explanation

Fetches hits from the HMMER (HMMPFAM) search output file.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt hmm\_score\_extract [ options ] HMMPFAM\_OUT}

Where HMMPFAM\_OUT is the HMMPFAM output file.

% 2. Options

\item{Options:}
\begin{description}
\item -E CUTOFF -- Define cutoff for acceptable E values (default: 0.01)
\item -s HMM\_ITEM -- Save the scores under the name HMM\_ITEM
\item -d -- Turn debuggin on. 
            This will create the file hmm\_scores.opt\_d\_flag with raw scores.
\end{description}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> hmm_score_extract -E 0.01 -s hits hmmpfam.out

 Processing HMMPFAM search output file

  No     Sequence                            E-score
 -----------------------------------------------------
 (   1)  LmjF05.1190@All                     2.70e-03
 (   2)  LmjF05.1190@GlycogenStarch          4.20e-03
 (   3)  LmjF05.0920@All                     7.50e-03

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} (with option -s) hmm\_score

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[hmm\_score2seq]{ \fbox{\tt hmm\_score2seq} }

\index{hmm\_score2seq}

% Concise explanation

Fetches and saves sequences whose ID's are given in the HMM scores
objects created by the command 'hmm\_score\_extract'.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt hmm\_score2seq [ options ] DBA\_FILE OUT\_FILE OBJ\_NAME}

Where DBA\_FILE is the sequence database, OUT\_FILE is the output file
with sequences (to be created), and OBJ\_NAME is the name under which
the scores were saved with 'hmm\_score\_extract'.

% 2. Options

\item{Options:}
\begin{description}
\item -w WIDTH -- Set the width of the sequence string per line written
to the OUT\_FILE (default: width=60)
\item -m MODEL -- Extract only sequences that matched a particular HMM
model. If this option is not activated all matches are written to
the output file and sequence IDs are written as SEQID\@PFAM\_MODEL.
If this option is activated the sequence IDs are written only as
SEQID.
\item -n NUMBER -- Crop sequences extracted to at most NUMBER of sequences.
\item -c -- Do NOT embed the matching model and maching score into sequence
comment.
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item Sequence database file DBA\_FILE must be in FASTA format.
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> hmm_score2seq LmjFmockup.pep hits.fas hits

 found 3 sequences to extract
 Processing the database 'LmjFmockup.pep'
 Sequences written to 'hits.fas'

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} hmm\_score

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ##############################################################
\section{Sequence motifs commands}
% ##############################################################

% ### NEW COMMAND ###

\subsection[motif\_load]{ \fbox{\tt motif\_load} }

\index{motif\_load}

% Concise explanation

Loads sequence motif.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt motif\_load [ options ] DBA\_FILE OBJ\_NAME}

 Where DBA\_FILE is the name of the database file. OBJ\_NAME is
 the internal YABBY name for this motif.

% 2. Options

\item{Options:}
\begin{description}
\item -f -- the file format is FASTA (default)
\item -b -- the file format is BLOCKS
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item A 'motif' object is internally identical to the 'sequence' object.
\item Only BLOCKS format as given by MEME output was tested.
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> motif_load -b m2.blocks m2

 Reading the file 'm2.blocks' ..
 11 sequence(s) found in the motif 'm2'.

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} motif

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[motif\_cmp]{ \fbox{\tt motif\_cmp} }

\index{motif\_cmp}

% Concise explanation

Compares two sequence motifs.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt motif\_cmp MOTIF1\_OBJ MOTIF2\_OBJ}

 Compares two motifs.  Two motifs are identical if they have
 the same number of sequences, the sequences have the same
 ID, and the sequences themselves are identical as strings.

% 2. Options

\item{Options:} {\em None}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> motif_cmp m2 m2_second

 Motifs 'm2' and 'm2_second' contain the same sequence IDs.
 Comparing the sequences...
 Motifs 'm2' and 'm2_second' are identical.

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} motif

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[motif\_meme]{ \fbox{\tt motif\_meme} }

\index{motif\_meme}

% Concise explanation

Extracts motifs from MEME text output files.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt motif\_meme MEME\_OUTPUT MOTIF\_NUMBER OBJ\_NAME}

 Reads the output file MEME\_OUTPUT, extracts motif number
 MOTIF\_NUMBER and saves motif as OBJ\_NAME.

% 2. Options

\item{Options:} {\em None}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> motif_meme meme.out 1 m1

 Reading MEME output 'meme.out' ..
 Motif 1 saved as 'm1'.

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} motif

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ##############################################################
\section{BLAST commands}
% ##############################################################

% ### NEW COMMAND ###

\subsection[blast]{ \fbox{\tt blast} }

\index{blast}

% Concise explanation

Runs NCBI BLAST against a database.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt blast [ options ] DBA\_FILE OBJ\_NAME}

 Where DBA\_FILE is the sequence database and OBJ\_NAME is the
 name of the sequence object which contains the query sequence.
 If OBJ\_NAME contains more than one sequence, all will be used
 in turn as a query sequence.

% 2. Options

\item{Options:}
\begin{description}
\item -E E\_VALUE -- Sets the expectation value for BLAST (default=0.01)
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item This command runs the NCBI program `blastall'
\item The full PATH to `blastall' is defined in yabby\_blast.pm
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> blast -E 5.0 LmjFmockup.pep cad3

 3 sequence(s) found in the object 'cad3'

 Now running BLAST ..
 BLASTing sequence 1 of 3 (Q53650_STAAU)
 Query sequence 'Q53650_STAAU'
 Database 'LmjFmockup.pep'
 Found 3 hits above the threshold (E=5.00)
 The best hit: 'LmjF05.1170'
 E-score = 2.22e+00

 BLASTing sequence 2 of 3 (Q97PJ0_STRPN)
 Query sequence 'Q97PJ0_STRPN'
 Database 'LmjFmockup.pep'
 Found 1 hits above the threshold (E=5.00)
 The best hit: 'LmjF05.0950'
 E-score = 2.92e+00

 BLASTing sequence 3 of 3 (P95773_STALU)
 Query sequence 'P95773_STALU'
 Database 'LmjFmockup.pep'
 No BLAST hits above the threshold (E=5.00) found.

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[blast\_info]{ \fbox{\tt blast\_info} }

\index{blast\_info}

% Concise explanation

Prints the information about the BLAST search previously
generated by the `blast' command.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt blast\_info OBJ\_NAME}

Where OBJ\_NAME is the name of an existing blast object.

% define OBJ\_NAME

% 2. Options

\item{Options:} {\em None}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> blast_info cad3_1

 Query sequence 'Q53650_STAAU'
 Database 'LmjFmockup.pep'
 Found 3 hits above the threshold (E=5.00)
 The best hit: 'LmjF05.1170'
 E-score = 2.22e+00

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} blast

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[blastg]{ \fbox{\tt blastg} }

\index{blastg}

% Concise explanation

Runs NCBI BLAST against a database and saves the best
hit for each sequence.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt blastg [ options ] DBA\_FILE OBJ\_NAME}

 Where DBA\_FILE is the sequence database and OBJ\_NAME
 is the name of the sequence object which contains
 sequences to be blasted. Each sequence is in turn
 blasted against the database, and the top hit is
 stored as BLASG object. This object contains the
 list of:

 SEQ\_ID DBA\_SEQ\_ID E\_VALUE

 Where SEQ\_ID is the sequence ID, DBA\_SEQ\_ID is the
 best hits database sequence ID, and E\_VALUE is the
 E-value of the match.

% 2. Options

\item{Options:}
\begin{description}
\item -E E\_VALUE -- Sets the expectation value for BLAST (default=0.01)
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item This command is experimental. Originally it was used
 to blast one genome against another, to obtain a quick
 estimate of the similarity between two genome.
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> blastg -E 5.0 LmjFmockup.pep cad3

 3 sequence(s) found in the object 'cad3'

 Now running BLAST ..
 BLASTing sequence 1 of 3 (Q53650_STAAU)
  top hit LmjF05.1170, E-score = 2.22e+00
 BLASTing sequence 2 of 3 (Q97PJ0_STRPN)
  top hit LmjF05.0950, E-score = 2.92e+00
 BLASTing sequence 3 of 3 (P95773_STALU)
  top hit None, E-score = -1.00e+00
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ##############################################################
\section{Protein three-dimensional structure commands}
% ##############################################################

% ### NEW COMMAND ###

\subsection[mol\_load]{ \fbox{\tt mol\_load} }

\index{mol\_load}

% Concise explanation

Loads a molecule from the PDB file.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt mol\_load [ options ] PDB\_FILE OBJ\_NAME}

Loads the molecule from the PDB\_FILE and saves it under
the name OBJ\_NAME.

% 2. Options

\item{Options:}
\begin{description}
\item -u -- require strict Protein Data Bank format when reading
 the PDB file. This amounts to requiring that residue names
 have maximum of three characters (columns 18,19, and 20) of
 an ATOM or HETATM record. By default this behavior is disabled,
 and four letter residue names are expected (columns 18,19,20
 and 21). This is safe in most cases as the extra column 21 is
 actually not defined in the strict Protein Data Bank format.
\end{description}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> mol_load 1BT0.pdb bto

 661 atoms found in the molecule 'bto'

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} mol

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[mol2seq]{ \fbox{\tt mol2seq} }

\index{mol2seq}

% Concise explanation

Creates the amino acid sequence from a molecule.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt mol2seq OBJ\_NAME}

where OBJ\_NAME is the name of an existing 'mol' object.

% 2. Options

\item{Options:}
\begin{description}
\item -f -- print to a file.
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item If no argument is given all will be printed.
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> mol2seq bto

 WARNING: a non-sequential residue:  201 ZN
 WARNING: residue 'ZN' does not have one letter code
...snip...
 WARNING: residue 'HOH' does not have one letter code
 153 residues found in the molecule 'bto'
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} mol

% 6. Objects 

\item{Creates objects:} seq

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[pdb\_conv]{ \fbox{\tt pdb\_conv} }

\index{pdb\_conv}

% Concise explanation

Converts Protein Data Bank coordinate files into XPLOR/CHARMM
 PDB format, with possible filtering

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt pdb\_conv [ options ] PDB\_INPUT PDB\_OUTPUT}

This command reads Protein Data Bank file PDB\_INPUT and writes
XPLOR/CHARMM PDB file PDB\_OUTPUT.

% 2. Options

\item{Options:}
\begin{description}
\item -u -- require strict Protein Data Bank format when reading
 the PDB file. This amounts to requiring that residue names
 have maximum of three characters (columns 18,19, and 20) of
 an ATOM or HETATM record. By default this behavior is disabled,
 and four letter residue names are expected (columns 18,19,20
 and 21). This is safe in most cases as the extra column 21 is
 actually not defined in the strict Protein Data Bank format
\item -f FORMAT -- use the format FORMAT when writing the PDB
 output file. Allowed formats are 'xplor' (default) or 'charmm'.
 The difference between the two is subtle, and occurs only for
 residues which have a residue number greater than 999
\item -l ALT\_LOC -- write atoms with the alternative location
 field equal to ALT\_LOC, together with those without ALT\_LOC
 label. In some structures only a subset of atoms is found in
 two alternative locations, and therefore only a subset of atoms
 has ALT\_LOC fields set to distinguish the two positions
\item -m CHAIN\_ID -- write only atoms with the chain ID equal
 to CHAIN\_ID
\item -i SEGID -- replace the segment name with SEGID
\item -h -- discard hydrogens, i.e. all atoms whose names begin with
 either the letter 'H' (case insensitive) or a number
\item -e -- discard HEATM records (by default HEATM records are
 included, and rewritten as ATOM records)
\item -r RBEGIN:OFFSET -- Add offset OFFSET to reside numbers
 starting with the residue number RBEGIN
\end{description}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[pdb\_model]{ \fbox{\tt pdb\_model} }

\index{pdb\_model}

% Concise explanation

Splits Protein Data Bank file with multiple models into
multiple XPLOR PDB files

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt pdb\_model [ options ] PDB\_INPUT MODEL\_ROOT}

 PDB\_INPUT is the Protein Data Bank file which contains
 multiple models (separated with MODEL/ENDMDL statements),
 and MODEL\_ROOT is the root name for the CHARMM/XPLOR
 PDB files to be created (one file per model). The final
 file names will be MODEL\_ROOT\_1.pdb, MODEL\_ROOT\_2.pdb,
 etc. until all models are exausted.

% 2. Options

\item{Options:}
\begin{description}
\item -u -- require strict Protein Data Bank format when reading
 the PDB file. This amounts to requiring that residue names
 have maximum of three characters (columns 18,19, and 20) of
 an ATOM or HETATM record. By default this behavior is disabled,
 and four letter residue names are expected (columns 18,19,20
 and 21). This is safe in most cases as the extra column 21 is
 actually not defined in the strict Protein Data Bank format
\item -f FORMAT -- use the format FORMAT when writing the PDB
 output file. Allowed formats are 'xplor' (default) or 'charmm'.
 The difference between the two is subtle, and occurs only for
 residues which have a residue number greater than 999
\item -l ALT\_LOC -- write atoms with the alternative location
 field equal to ALT\_LOC, together with those without ALT\_LOC
 label. In some structures only a subset of atoms is found in
 two alternative locations, and therefore only a subset of atoms
 has ALT\_LOC fields set to distinguish the two positions
\item -m CHAIN\_ID -- write only the molecule with the chain ID
 equal to CHAIN\_ID
\item -i SEGID -- replace the segment name with SEGID
\item -h -- discard hydrogens, i.e. all atoms whose names begin with
 either the letter 'H' (case insensitive) or a number
\item -e -- discard HEATM records (by default HEATM records are
 included, and rewritten as ATOM records)
\item -r RBEGIN:OFFSET -- Add offset OFFSET to reside numbers
 starting with the residue number RBEGIN
\end{description}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item The file 1C3T.pdb contain 20 structures of ubiquitin, available
from the RCSB Protein Data Bank.
\begin{verbatim}
yabby> pdb_model 1C3T.pdb ubq_

 working on model  1 (creating 'ubq_1.pdb')
 working on model  2 (creating 'ubq_2.pdb')
 working on model  3 (creating 'ubq_3.pdb')
 working on model  4 (creating 'ubq_4.pdb')
 working on model  5 (creating 'ubq_5.pdb')
 working on model  6 (creating 'ubq_6.pdb')
 working on model  7 (creating 'ubq_7.pdb')
 working on model  8 (creating 'ubq_8.pdb')
 working on model  9 (creating 'ubq_9.pdb')
 working on model 10 (creating 'ubq_10.pdb')
 working on model 11 (creating 'ubq_11.pdb')
 working on model 12 (creating 'ubq_12.pdb')
 working on model 13 (creating 'ubq_13.pdb')
 working on model 14 (creating 'ubq_14.pdb')
 working on model 15 (creating 'ubq_15.pdb')
 working on model 16 (creating 'ubq_16.pdb')
 working on model 17 (creating 'ubq_17.pdb')
 working on model 18 (creating 'ubq_18.pdb')
 working on model 19 (creating 'ubq_19.pdb')
 working on model 20 (creating 'ubq_20.pdb')

 20 models found

yabby>
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ##############################################################
\section{EMBOSS commands}
% ##############################################################

% ### NEW COMMAND ###

\subsection[emboss\_needle]{ \fbox{\tt emboss\_needle} }

\index{emboss\_needle}

% Concise explanation

Extracts sequences which have the highest similarity from
he output of the EMBOSS program 'needle'.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt emboss\_needle NEEDLE\_OUTPUT NN}

  Where NEEDLE\_OUTPUT is the output file of the program 'needle',
  and NN is the number of highest alignments to report (as given
  by the 'Similarity' line in the needle output).

% 2. Options

\item{Options:} {\em None}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> emboss_needle needle.out 3

 Processing the file 'needle.out' ..

 (1) Q45153_BACFI:LmjF05.1170, Similarity: 26.6
 (2) Q45153_BACFI:LmjF05.1120, Similarity: 16.4
 (3) Q45153_BACFI:LmjF05.1040, Similarity: 15.0

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####


% ### NEW COMMAND ###

\subsection[emboss\_needl2]{ \fbox{\tt emboss\_needl2} }

\index{emboss\_needl2}

% Concise explanation

For each sequence in a set finds the best matching sequence
from the database by running the EMBOSS program needle.
Uses the information on sequence similarity reported by
needle.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt emboss\_needl2 SEQ\_QUERY SEQ\_DBA OBJ\_NAME}

Where SEQ\_QUERY is an existing yabby sequence object, SEQ\_DBA
is the FASTA database file with sequences to be compared, and
OBJ\_NAME is the name of the 'needl2' object to be created.

% 2. Options

\item{Options:}
\begin{description}
{\em None} - Uncomment this and delete line below if no notes
\end{description}

% 3. Notes

\item{Notes:}
\begin{enumerate}
\item This command requires the EMBOSS program 'needle'
\end{enumerate}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> emboss_needl2 ec057 Ecoli_lab.fas ec

 'ec057' contains 9 sequence(s)
 Working on sp|P36546|OMPX_ECOLI
Needleman-Wunsch global alignment.
 Working on tr|Q8X8K6|Q8X8K6
Needleman-Wunsch global alignment.
 Working on sp|P39170|UP05_ECOLI
Needleman-Wunsch global alignment.
 Working on tr|Q8XDF1|Q8XDF1
Needleman-Wunsch global alignment.
 Working on sp|P58603|OMPT_ECO57
[... further output deleted ...]
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} seq (for SEQ\_QUERY)

% 6. Objects 

\item{Creates objects:} needl2

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ##############################################################
\section{Miscellaneous commands}
% ##############################################################

% ### NEW COMMAND ###

\subsection[pfam\_fetch]{ \fbox{\tt pfam\_fetch} }

\index{pfam\_fetch}

% Concise explanation

Fetches an entry from the PFAM database file.

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt pfam\_fetch PFAM\_CODE PFAM\_DBA FILE\_NAME}

 Where PFAM\_CODE is the PFAM accession code, PFAM\_DBA is
 the PFAM database, and FILE\_NAME is the file to save
 the entry. For example, to fetch the entry PF00293
 from the PFAM database Pfam-A.seed, and save it as
 PF00293.seed:

 pfam\_fetch PF00293 Pfam-A.seed PF00293.full

% 2. Options

\item{Options:} {\em None}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} {\em None}

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

% ### NEW COMMAND ###

\subsection[sprot\_split]{ \fbox{\tt sprot\_split} }

\index{sprot\_split}

% Concise explanation

Splits large sequence database written in SWISS-PROT format
into smaller files. This command is useful when a large SWISS-PROT
file needs to be reformatted with an external programs (such as
'sreformat'), which have a limitation on the file size. 

% Command description

\begin{description}

% 1. Usage

\item{Usage:}

{\tt sprot\_split [ options ] DBA\_FILE}

 Where DBA\_FILE is the name of the sequence database file in
 the SWISS-PROT format. The output files are named DBA\_FILE.1,
 DBA\_FILE.2, etc.

% 2. Options

\item{Options:}
\begin{description}
\item -n NLINES -- split the database into files approx NLINES
 each (default: NLINES = 20000000).
\end{description}

% 3. Notes

\item{Notes:} {\em None}

% 4. Examples 

\item{Examples:}
\begin{enumerate}

\item
\begin{verbatim}
yabby> sprot_split uniprot_trembl.dat
 Reading the database file 'uniprot_trembl.dat' ..
 The number of lines in the database: 204071661
 -> Creating 'uniprot_trembl.dat.1'
 -> Creating 'uniprot_trembl.dat.2'
 -> Creating 'uniprot_trembl.dat.3'
 -> Creating 'uniprot_trembl.dat.4'
 -> Creating 'uniprot_trembl.dat.5'
 -> Creating 'uniprot_trembl.dat.6'
 -> Creating 'uniprot_trembl.dat.7'
 -> Creating 'uniprot_trembl.dat.8'
 -> Creating 'uniprot_trembl.dat.9'
 -> Creating 'uniprot_trembl.dat.10'
 -> Creating 'uniprot_trembl.dat.11'

\end{verbatim}

\end{enumerate}

% 5. Requirements 

\item{Requirements:} {\em None}

% 6. Objects 

\item{Creates objects:} A number of smaller sequence database file.

% 7. System scripts

\item{System scripts:} {\em None}

\end{description}

% ### END OF NEW COMMAND ####

